home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 2000 August: Tool Chest / Dev.CD Aug 00 TC Disk 2.toast / pc / sample code / human interface toolbox / htmlsample / history.h < prev    next >
Encoding:
C/C++ Source or Header  |  2000-06-23  |  4.6 KB  |  135 lines
  1. /*
  2.     file History.h
  3.     
  4.     Description:
  5.     This file contains routine prototypes and type declarations that can
  6.     be used to access the routines defined in History.c  These routines
  7.     are used to store visitled links.
  8.     
  9.     HTMLSample is an application illustrating how to use the new
  10.     HTMLRenderingLib services found in Mac OS 9. HTMLRenderingLib
  11.     is Apple's light-weight HTML rendering engine capable of
  12.     displaying HTML files.
  13.  
  14.     by John Montbriand, 1999.
  15.  
  16.     Copyright: © 1999 by Apple Computer, Inc.
  17.     all rights reserved.
  18.     
  19.     Disclaimer:
  20.     You may incorporate this sample code into your applications without
  21.     restriction, though the sample code has been provided "AS IS" and the
  22.     responsibility for its operation is 100% yours.  However, what you are
  23.     not permitted to do is to redistribute the source as "DSC Sample Code"
  24.     after having made changes. If you're going to re-distribute the source,
  25.     we require that you make it clear in the source that the code was
  26.     descended from Apple Sample Code, but that you've made changes.
  27.     
  28.     Change History (most recent first):
  29.     10/16/99 created by John Montbriand
  30. */
  31.  
  32.  
  33. #ifndef __HISTORY__
  34. #define __HISTORY__
  35.  
  36. #include <Types.h>
  37. #include <Menus.h>
  38.  
  39.  
  40. /* HistoryDataHandle defines the data type we are using
  41.     for storing historical information about visited links.
  42.     A history is maintained as a list/stack where we can
  43.     move backwards and forwards referencing elements as
  44.     required.  The only difference between a history and
  45.     a stack is that if we add a new element to the history,
  46.     then all elements beyond the current reference are
  47.     deleted before the new element is added. */
  48. typedef struct HistoryData HistoryData;
  49. typedef HistoryData *HistoryDataPtr, **HistoryDataHandle;
  50.  
  51.  
  52. /* NewHistory creats a new history and returns
  53.     a handle to it. */
  54. HistoryDataHandle NewHistory(void);
  55.  
  56.  
  57. /* DisposeHistory disposes of a history and all of the
  58.     structures allocated for it. */
  59. void DisposeHistory(HistoryDataHandle hd);
  60.  
  61.  
  62. /* AddToHistory adds a new element to the history.  Both
  63.     the URL and the printed representation of its url
  64.     are stored.  NOTE:  if we have called GoBack a few times
  65.     before this call, then those previously viewed items
  66.     are removed from the history. This is so if we choose
  67.     GoBack again, then we will arrive at the same link we
  68.     are looking at now.  */
  69. OSErr AddToHistory(HistoryDataHandle hd, char const* url, StringPtr printName);
  70.  
  71.  
  72. /* InHistory returns true if the URL is among the urls
  73.     currently stored in the history. */
  74. Boolean InHistory(HistoryDataHandle hd, char const* url);
  75.  
  76. /* CanGoBack returns true if it makes sense to call the
  77.     GoBack command.  i.e. if there are one or more links
  78.     in the history beyond the current one. */
  79. Boolean CanGoBack(HistoryDataHandle hd);
  80.  
  81. /* GoBack copies the previous url in the history
  82.     into a new handle and returns that handle in
  83.     *url.  It is the caller's responsibility to dispose
  84.     of the handle after it has been used. */
  85. OSErr GoBack(HistoryDataHandle hd, Handle *url);
  86.  
  87.  
  88. /* CanGoForward returns true if it makes sense to call the
  89.     GoForward command.  i.e. if there are one or more links
  90.     in the history ahead of the current one.  This can only
  91.     happen after the user has chosen GoBack one or more
  92.     times. */
  93. Boolean CanGoForward(HistoryDataHandle hd);
  94.  
  95.  
  96. /* GoForward copies the next url in the history
  97.     into a new handle and returns that handle in
  98.     *url.  It is the caller's responsibility to dispose
  99.     of the handle after it has been used. */
  100. OSErr GoForward(HistoryDataHandle hd, Handle *url);
  101.  
  102.  
  103. /* CanGoHome returns true if it makes sense to call the
  104.     GoHome command.  i.e. if there are one or more links
  105.     in the history.  This can only happen after AddToHistory
  106.     has been called one or more times. */
  107. Boolean CanGoHome(HistoryDataHandle hd);
  108.  
  109.  
  110. /* GoBack copies the first url in the history
  111.     into a new handle and returns that handle in
  112.     *url.  It is the caller's responsibility to dispose
  113.     of the handle after it has been used. */
  114. OSErr GoHome(HistoryDataHandle hd, Handle *url);
  115.  
  116.  
  117. /* AppendHistoryToMenu rebuilds the Go menu adding items to the
  118.     bottom of the menu according to the items in the
  119.     history.  The names of the items are the same as
  120.     the printNames provided in the AddToHistory command. */
  121. OSErr AppendHistoryToMenu(HistoryDataHandle hd, MenuHandle theMenu);
  122.  
  123.  
  124. /* GoToMenuItem copies the itemIndex'th url in the history
  125.     into a new handle and returns that handle in
  126.     *url.  It is the caller's responsibility to dispose
  127.     of the handle after it has been used.  This routine
  128.     should only be called after a menu selection has
  129.     been made in a menu built by AppendHistoryToMenu.  */
  130. OSErr GoToMenuItem(HistoryDataHandle hd, Handle *url, short itemIndex);
  131.  
  132.  
  133. #endif
  134.  
  135.